package net.cassite.daf4j.resource;

import java.io.InputStream;
import java.util.Collection;
import java.util.List;

/**
 * the source of resources
 */
public interface Source {
        /**
         * separator for the location, e.g. "/"
         *
         * @return the separator
         * @throws Exception possible exceptions
         */
        String separator() throws Exception;

        /**
         * determines whether the location exists
         *
         * @param location location
         * @return true if exists, false otherwise
         * @throws Exception possible exceptions
         */
        boolean exists(String location) throws Exception;

        /**
         * determines whether the location have sub locations
         *
         * @param location location
         * @return true if have sub locations
         * @throws Exception possible exceptions
         */
        boolean haveSubLocations(String location) throws Exception;

        /**
         * locations inside the given location
         *
         * @param location location
         * @return list of locations
         * @throws Exception possible exceptions
         */
        List<String> subLocations(String location) throws Exception;

        /**
         * get last modified time of a location
         *
         * @param location location
         * @return last modified time (long)
         * @throws Exception possible exceptions
         */
        long lastModifiedTime(String location) throws Exception;

        /**
         * get creating time of a location
         *
         * @param location location
         * @return creating time (long)
         * @throws Exception possible exceptions
         */
        long creatingTime(String location) throws Exception;

        /**
         * get resource length in byte
         *
         * @param location location
         * @return resource length in byte
         * @throws Exception possible exceptions
         */
        long length(String location) throws Exception;

        /**
         * get input stream of designated resource
         *
         * @param location location
         * @return create time
         * @throws Exception possible exceptions
         */
        InputStreamProvider provideStream(String location) throws Exception;

        /**
         * write all the stream bytes into the resource
         *
         * @param location    location to write stream on
         * @param inputStream input stream
         * @throws Exception possible exceptions
         */
        void write(String location, InputStream inputStream) throws Exception;

        /**
         * move the location to another location
         *
         * @param originalLocation original location
         * @param newLocation      new location
         * @throws Exception possible exceptions
         */
        void move(String originalLocation, String newLocation) throws Exception;

        /**
         * delete the location
         *
         * @param locations locations to delete
         * @throws Exception possible exceptions
         */
        void delete(Collection<String> locations) throws Exception;
}
